Fossil: Usando y configurando el Wiki

Sigo adelante con la serie de articulos sobre el gestor de versiones Fossil. En entradas anteriores he comentado los pasos necesarios para arrancar y configurar el servidor.

Esta entrada va a estar centrada en el wiki, tanto en las acciones básicas de uso del wiki como en la modificación del aspecto del mismo.

Creando la página por defecto del wiki

En la documentación de Fossil se indica que cuando accedemos a la URL del servidor se muestra automáticamente la página home. Es decir, si introducimos:

http://192.168.1.200:8081/

el servidor muestra:

http://192.168.1.200:8081/home

En mis pruebas, sin embargo, el servidor redirige a

http:\\192.168.1.200:8081/index

Al acceder al entorno web creado por Fossil se muestra una página en blanco (Empty Page). Para empezar a dotar de contenido a nuestro wiki, vamos a Wiki y seleccionamos la opción Create new Wiki Page de la lista de opciones que se nos muestra.

Podría parecer lógico que para crear esta página por defecto del servidor tuviéramos que crear una página del wiki llamada home (o index), pero no; el nombre de la página por defecto del wiki debe ser el nombre del proyecto Fossil. Recuerda que este nombre se especifica en Admin -> Configuration.
En mi caso, el nombre del proyecto es Fossil Wiki, de manera que éste debe ser el nombre de la página que voy a crear en el wiki.

Creando la página por defecto del wiki.

Editar contenido del wiki

Utilizando las barras de herramientas del modo WYSIWYG la introducción de contenido en el wiki es muy fácil, por lo que cualquiera puede añadir, corregir y mejorar la documentacion del wiki (siempre que tenga los permisos necesarios para ello).

A través de los desplegables de las diferentes barras de herramientas podemos crear encabezados de diferentes tamaños, cambiar el tipo de fuente, su tamaño e incluso el color con el que se muestra cualquier parte del contenido de la página del wiki.

También encontramos los botones habituales de cualquier procesador de texto para aplicar negritas, cursivas, alinear texto, indentarlo, etc.

Es decir, cualquier usuario con los permisos adecuados que esté acostumbrado a redactar texto en un procesador de texto o a usar el correo electrónico será capaz de editar información en el wiki sin problemas.

Esta facilidad de uso hace que el uso de un wiki alcance a usuarios no técnicos, de manera que el ámbito de utilización del wiki es enorme.

El uso de un entorno similar a un procesador de texto hace que no sea necesario ningún aprendizaje previo.
Los usuarios con un perfil más técnico o acostumbrados a escribir código HTML pueden aprender las reglas del wiki y utilizar el modo de edición de HTML puro sin que haya que realizar cambios en la configuración del wiki.

Inclusión de imágenes

El principal inconveniente del Wiki es que no proporciona una manera sencilla de subir imágenes (por ejemplo, capturas de pantalla desde nuestro ordenador). Es posible enlazar imágenes desde una URL (desde internet) y también desde el sistema de control de versiones (enlazando a su número de revisión). Sin embargo, esto puede suponer un problema si queremos que usuarios de perfil no-técnico incorporen información al wiki.

Esta carencia es especialmente llamativa si tenemos en cuenta que existe la posibilidad de adjuntar ficheros y comentarios a cualquier página del wiki (si tenemos permisos para ello) y que los ficheros adjuntos pueden ser cualquier tipo de archivo (en particular, imágenes).

Ejemplo de imagen adjunta a una página del wiki.

Al visualizar la imagen adjuntada a la página del wiki el wiki le asigna un número de artefacto, es decir, una referencia única como a cualquier otro elemento controlado por el sistema de versiones. Aunque en la documentación se indica que se puede enlazar a cualquier artefacto a traves de su referencia, no he conseguido enlazar a las imágenes con las que he probado.

Podemos adjuntar imágenes a las páginas pero no podemos insertarlas en la página de forma directa.

Enlazando a otras páginas del wiki

El método de enlazado automático de páginas en los primeros wikis es conocido como camel case, que traduciré como escritura escalonada. La ventaja de este sistema es su simplicidad: unimos dos o más palabras, manteniendo las mayúsculas iniciales en cada una de ellas. De esta manera, PrimeraPagina se convierte en un enlace a la página del wiki de nombre Primera Pagina.

Pese a su sencillez, este sistema presenta varios problemas. ¿Qué hacemos para enlazar a una página cuyo nombre sea una sola palabra? En otros casos, palabras como JavaScript, iPod o McDonalds también se convierten en enlaces automáticamente, incluso cuando quizás no queremos enlazarlas... Finalmente, este sistema también presenta problemas con los acentos o con combinaciones de palabras unidos por conjunciones como la 'y', por ejemplo...

Por todo ello, aunque en muchos wikis todavía se permite utilizar este tipo de nomenclatura para crear enlaces entre páginas, su uso está desaconsejado y es preferible utilizar enlaces mediante corchetes (de algún tipo).

En el wiki de Fossil los enlaces se pueden insertar en una página wiki de dos formas: la primera, encerrando el nombre de la página entre corchetes simples. Es decir, si queremos enlazar con una página cuyo nombre es Enlaces en el wiki, escribimos:

... cuyo nombre es [Enlaces en el wiki], escribimos ...

Esta nomenclatura nos permite enlazar de forma ágil entre páginas de nuestro wiki, simplemente utilizando el nombre de la página.

La única pega es que este método no funciona en la vista WYSIWYG.

El segundo método es utilizar la etiqueta  de HTML para crear el enlace entre las páginas. Este método tiene la ventaja de que permite utilizar el botón de enlace presente en la barra de de herramientas de edición del wiki.

En este caso el wiki no realiza la conversión automática del nombre de la página del wiki a un enlace, por lo que debemos introducir la dirección de la página a la que queremos enlazar realizando esa conversión de forma manual.

Es decir, si estamos escribiendo en el wiki y queremos enlazar con la página principal, llamada Fossil Wiki, pulsamos el botón de enlace en la barra de herramientas y en la caja de texto introducimos:

/wiki?name=Fossil+Wiki

lo que da lugar a un enlace de la forma:

... un enlace a la página principal Fossil Wiki ...

Este es uno de los pocos inconvenientes de utilizar el entorno WYSIWYG a la hora de redactar la documentación.

Siempre podemos obtener lo mejor de los dos modos de edición cambiando entre uno y otro mediante el desplegable Edit Mode: y cambiar entre WYSIWYG y Raw HTML.

Facilitando el uso de la búsqueda en el wiki

Una de las funciones que uso más a menudo en el wiki es la de búsqueda. En la versión actual el wiki sólo permite buscar en los títulos de las páginas. Espero que en las próximas versiones la búsqueda se amplíe al contenido de las páginas del wiki.

Hasta que solucionan el problema, podemos facilitar el acceso al formulario de búsqueda. En la plantilla por defecto del wiki el buscador no es directamente accesible, sino que primero hay que pulsar sobre el enlace Wiki de la barra superior.

Modificando el encabezado o el pie de página del wiki podemos añadir el formulario de búsqueda en un lugar más accesible copiando el código:

<form action="/wfind" method="get">
    Buscar en los títulos del wiki:
    <input name="title" type="text" />
    <input type="submit" />
</form>

Caja de búsqueda bajo el encabezado del wiki

Otras modificaciones

Fossil permite modificar prácticamente cualquier aspecto del entorno del wiki. En la página de documentación de Fossil, Fossil Cookbok se muestran diferentes recetas para realizar modificaciones concretas al entorno del wiki sugeridas por los usuarios. Una de estas recetas muestra cómo utilizar diferentes editores Javascript -como TinyMCE o MarkItUp- en vez del editor WYSIWYG por defecto del wiki. Como estos editores son facilmente configurables, podemos adaptarlos al nivel y estilo de los integrantes de nuestro equipo de trabajo. El procedimiento está descrito con detalle en la página de Fossil, pero utiliza una técnica general que resulta interesante tener en mente a la hora de realizar modificaciones del wiki: añadir los componentes del editor javascript -en este caso- al sistema de control de versiones y enlazarlos utilizando las mismas urls que se utilizan para la documentación incrustada:

{IP_Servidor_FOSSIL}/doc/{version}/{nombre_fichero}

Donde {version} puede ser:

• tip: última versión del fichero
• identificador del artefacto: para mostrar una revisión concreta del fichero
• nombre_rama: para utilizar la versión del fichero de una rama concreta del sistema de control de versiones
• ckout: versión de la última versión en nuestra copia local del SCV

Así podemos utilizar la URL que apunta a /doc/tip/... en nuestra plantilla para hacer referencia a la última versión de las bibliotecas de jQuery que hayamos añadido al SCV, por ejemplo. De forma paralela podemos revisar la compatibilidad de la plantilla con nuevas versiones de la biblioteca de funciones -e incluso, con otras bibliotecas alternativas- en una rama de desarrollo sin temor a romper nada en la plantilla de producción. A diferencia de lo que he comentado con las imágenes, creo que en este caso la sinergia entre el wiki y el SCV integrados en Fossil es positiva, ya que la creación o mantenimiento de las plantillas del wiki es una tarea más orientada a un perfil técnico y no para un usuario final del wiki.

Modificando el aspecto del entorno web

Del mismo modo que hemos añadido el formulario de búsqueda a la plantilla para facilitar el acceso a la búsqueda, Fossil permite modificar el aspecto del wiki mediante la modificación del encabezado (header), pie (footer), el logo y el estilo aplicado al sitio (CSS).

La modificación de las CSS y el logo es únicamente estética: nos permite adecuar el entorno web de Fossil a la imagen corporativa o a nuestros gustos personales, por ejemplo.

En el header podemos modificar las opciones que aparecen en la barra superior de la web y añadir, por ejemplo, el enlace a la documentación incrustada en vez del enlace al wiki, en caso de usarla. Las opciones que se muestran en el encabezado dependen de los permisos del usuario que accede a la web, de manera que quizás lo más sencillo sea dejarlo tal cual.

En el footer, por defecto, sólo aparece una cadena que con información relativa al servidor (versión, fecha de creación, etc.) Estos datos se muestran utilizando unas variables internas usadas por el servidor Fossil; estas variables -y muchas más- están disponibles a través del lenguaje de script TH1 (descrito en el manual Fossil Scripting Language).

De nuevo, en caso de modificar el footer lo habitual sea incluir información de contacto del administrador y quizás un enlace a las condiciones de confidencialidad o política de uso del wiki, en un entorno empresarial. 

Un ejemplo de lo que puede conseguirse modificando la hoja de estilos CSS y la plantilla del wiki: 

Página de Administración del wiki después de modificar la apariencia utilizando Twitter Bootstrap.

Resumen

En esta entrada he comentado cómo acceder al wiki y configurar la página que se muestra por defecto.

También he comentado cómo facilitar el proceso de edición mediante la activación de la barra de herramientas en el modo WYSIWYG. He comentado un par de puntos mejorables del wiki, en mi opinión, como son la subida de imágenes y la creación de enlaces, con sus ventajas y desventajas.

Finalmente he comentado algunas de las modificaciones que pueden realizarse en el wiki para facilitar su uso -colocar la caja de búsqueda en la cabecera del wiki- o para cambiar la apariencia del wiki.

En el próximo y último artículo de la serie sobre Fossil me centraré en los clientes gráficos para este completo y ligero gestor de versiones.